package it.infodea.tapestrydea.services.jcr;

import javax.jcr.Credentials;
import javax.jcr.Session;

/**
 * Questo servizio permette di accedere alla sessione jcr 
 * in molti modi differenti a seconda del meccanismo di autenticazione
 * che si preferisce.
 * Ha un solo metodo con diversi overload che rappresentano le varie opzioni
 * <code>public Session getSession()</code> e <code>public Session getSession(String workspace);</code>
 * prevedono che i dati di autenticazione siano reperibili dall'implementazione (per esempio si potrebbero
 * trovare nella sessione utente o in un state object (ASO))
 * <code>public Session getSession(String user, String password);</code> e 
 * <code>public Session getSession(String user, String password, String workspace);</code>
 * usano i dati in input e creano l'oggetto Credential per l'autenticazione alla sessione
 * del repository.
 * infine 
 * <code>public Session getSession(Credentials credentials);</code> e 
 * <code>public Session getSessionCredentials credentials, String workspace);</code>
 * permettono di passare un oggetto di tipo <code>Credentials</code> del tipo desiderato
 * consentendo l'uso di qualunque sistema di security jaas compliant.
 * @author bobpuley
 *
 */
public interface JcrSessionProviderService {
	
	/**
	 * Reperisce le informazioni per l'autenticazione dell'utente
	 * al repository e crea un oggetto <code>SimpleCredentials</code>
	 * per autenticarsi alla sessione jcr.
	 * @return restituisce la sessione per l'utente sul workspace di default (il cui nome in jackrabbit � <i>default</i>) o null.
	 */
	public Session getSession();

	/**
	 * Reperisce le informazione per l'autenticazione dell'utente
	 * al repository e crea un oggetto <code>SimpleCredentials</code>
	 * per autenticarsi alla sessione jcr.
	 * @param workspace il nome del workspace richiesto
	 * @return restituisce la sessione per l'utente sul workspace richiesto o null se le credenziali 
	 * non sono valide o il workspace non esiste o esiste ma l'utente non ha le credenziali per accedervi.
	 */
	public Session getSession(String workspace);
	
	/**
	 * Crea un oggetto <code>SimpleCredentials</code>, con
	 * la user e la password ricevute, per autenticarsi alla sessione jcr.
	 * @param user lo username dell'utente che si vuole autenticare alla sessione jcr
	 * @param password la password dell'utente che si vuole autenticare alla sessione jcr
	 * @return restituisce la sessione per l'utente sul workspace di default (il cui nome in jackrabbit � <i>default</i>) o null.
	 */
	public Session getSession(String user, String password);
	
	/**
	 * Crea un oggetto <code>SimpleCredentials</code>, con
	 * la user e la password ricevute, per autenticarsi alla sessione jcr.
	 * @param user lo username dell'utente che si vuole autenticare alla sessione jcr
	 * @param password la password dell'utente che si vuole autenticare alla sessione jcr
	 * @param workspace il nome del workspace richiesto
	 * @return restituisce la sessione per l'utente sul workspace richiesto o null se le credenziali 
	 * non sono valide o il workspace non esiste o esiste ma l'utente non ha le credenziali per accedervi.
	 */
	public Session getSession(String user, String password, String workspace);
	
	/**
	 * Si autentica al repository passandogli le credentials ricevute 
	 * @param credentials le credentials per accreditarsi al repository
	 * @return restituisce la sessione per l'utente sul workspace di default (il cui nome in jackrabbit � <i>default</i>) o null.
	 */
	public Session getSession(Credentials credentials);
	
	/**
	 * Si autentica al repository passandogli le credentials ricevute e il workspace
	 * scelto
	 * @param credentials le credentials per accreditarsi al repository
	 * @param workspace il nome del workspace richiesto
	 * @return restituisce la sessione per l'utente sul workspace richiesto o null se le credenziali 
	 * non sono valide o il workspace non esiste o esiste ma l'utente non ha le credenziali per accedervi.
	 */
	public Session getSession(Credentials credentials, String workspace);
}
